home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / roboticsdp / autodocs / minissc.doc next >
Text File  |  2000-02-28  |  19KB  |  658 lines
  1. TABLE OF CONTENTS
  2.  
  3. minissc.library/ssc_AMove
  4. minissc.library/ssc_ChangeControllerSettings
  5. minissc.library/ssc_ChangeServoSettings
  6. minissc.library/ssc_ControllerRange
  7. minissc.library/ssc_ControllerStatus
  8. minissc.library/ssc_FreeController
  9. minissc.library/ssc_FreeServo
  10. minissc.library/ssc_GetAPosition
  11. minissc.library/ssc_GetPosition
  12. minissc.library/ssc_Move
  13. minissc.library/ssc_OccupyController
  14. minissc.library/ssc_OccupyServo
  15. minissc.library/ssc_Reset
  16. minissc.library/ssc_ResetAll
  17. minissc.library/ssc_ServoRange
  18. minissc.library/ssc_ServoStatus
  19. minissc.library/ssc_SetAPosition
  20. minissc.library/ssc_SetPosition
  21. minissc.library/ssc_AMove                                     minissc.library/ssc_AMove
  22.  
  23.  NAME
  24.      ssc_AMove -- Moves servo in proportion to current position
  25.  
  26.  SYNOPSIS
  27.      position = ssc_AMove( servo, displacement )
  28.      D0                    D0     D1
  29.  
  30.      int ssc_AMove(int servo, int displacement);
  31.  
  32.  FUNCTION
  33.      This function moves servo in proportion to its current position.
  34.      Negative displacement value moves servo anticlockwise and positive value
  35.      clockwise.
  36.      When called, the related servo will be moved to the calculated position
  37.      as quickly as possible.
  38.  
  39.  INPUTS
  40.      servo - servo's ID number (0-254)
  41.      displacement - displacement value:
  42.          negative value = moves servo anticlockwise the amount of given
  43.          absolute units
  44.          posisitive value = moves servo clockwise the amount of given
  45.          absolute units
  46.  
  47.  RESULT
  48.      position - new servo position:
  49.          -1 = invalid servo ID number
  50.          -2 = calculated new servo position is out of range
  51.  
  52.  NOTES
  53.      Displacement value refers to an absolute position value. See
  54.      SetAPosition() function.
  55.  
  56.  SEE ALSO
  57.      ssc_Move()
  58.      ssc_SetAPosition()
  59.  
  60. minissc.library/ssc_ChangeControllerSettingsinissc.library/ssc_ChangeControllerSettings
  61.  
  62.  NAME
  63.      ssc_ChangeControllerSettings -- Changes controller settings
  64.  
  65.  SYNOPSIS
  66.      error = ssc_ChangeControllerSettings( cntroller, commmode, ctrlmode )
  67.      D0                                    D0         D1        D2
  68.  
  69.      int ssc_ChangeControllerSettings(int cntroller, int commmode, int ctrlmode);
  70.  
  71.  FUNCTION
  72.      You can change controller settings by using this function.
  73.      See function ssc_OccupyController() for more information about
  74.      controller settings.
  75.  
  76.  INPUTS
  77.      cntroller - controller's ID number (0-31)
  78.      commmode - communication rate:
  79.          SSC_COMMMODE_LOW  = low; baud rate is 2400
  80.          SSC_COMMMODE_HIGH = high; baud rate is 9600
  81.      ctrlmode - range of motion:
  82.          SSC_CTRLMODE_NARROW = narrow;
  83.              allows 90° movements with the accuracy of 0.36°
  84.          SSC_CTRLMODE_WIDE   = wide;
  85.              allows 180° movements with the accuracy of 0.72°
  86.  
  87.  RESULT
  88.      error - an error code:
  89.          0 = no errors
  90.          1 = can't change settings. Controller is not occupied
  91.          2 = parameter(s) out of range
  92.  
  93.  NOTES
  94.      Controller must be occupied before settings can be changed.
  95.  
  96.  SEE ALSO
  97.      ssc_ChangeServoSettings()
  98.      ssc_OccupyController()
  99.  
  100. minissc.library/ssc_ChangeServoSettings         minissc.library/ssc_ChangeServoSettings
  101.  
  102.  NAME
  103.      ssc_ChangeServoSettings -- Changes servo settings
  104.  
  105.  SYNOPSIS
  106.      error = ssc_ChangeServoSettings( servo, range)
  107.      D0                               D0     D1
  108.  
  109.      int ssc_ChangeServoSettings(int servo, float range);
  110.  
  111.  FUNCTION
  112.      You can change servo settings by using this function.
  113.      See function ssc_OccupyServo() for more information about servo settings.
  114.  
  115.  INPUTS
  116.      servo - servo's ID number (0-15)
  117.      range - range of motion (0-180)
  118.  
  119.  RESULT
  120.      error - an error code:
  121.          0 = no errors
  122.          1 = invalid servo number
  123.          2 = can't change settings. Servo is not ready
  124.          3 = invalid range
  125.  
  126.  NOTES
  127.      Servo must be occupied before settings can be changed.
  128.  
  129.  SEE ALSO
  130.      ssc_ChangeControllerSettings()
  131.      ssc_OccupyServo()
  132.  
  133. minissc.library/ssc_ControllerRange                 minissc.library/ssc_ControllerRange
  134.  
  135.  NAME
  136.      ssc_ControllerRange -- Gets controller's motion range
  137.  
  138.  SYNOPSIS
  139.      range = ssc_ControllerRange( cntroller )
  140.      D0                           D0
  141.  
  142.      float ssc_ControllerRange(int cntroller);
  143.  
  144.  FUNCTION
  145.      This function reads controller's motion range. Result is the current
  146.      range in degrees.
  147.  
  148.  INPUTS
  149.      cntroller - controller's ID number (0-31)
  150.  
  151.  RESULT
  152.      range - controller's motion range:
  153.          -1  = controller not available
  154.          90  = narrow range
  155.          180 = wide range
  156.  
  157.  NOTES
  158.      Mini SSC II does not support range queries or any kind of feedback.
  159.      Range information provided by this function is therefore based on the
  160.      software settings (minissc.library settings) and not on the actual hardware
  161.      settings.
  162.      You should always make sure that software and hardware settings match.
  163.      Otherwise servos will be mispositioned.
  164.  
  165.  SEE ALSO
  166.      ssc_OccupyController()
  167.      ssc_ServoRange()
  168.  
  169. minissc.library/ssc_ControllerStatus               minissc.library/ssc_ControllerStatus
  170.  
  171.  NAME
  172.      ssc_ControllerStatus -- Gets controller's status
  173.  
  174.  SYNOPSIS
  175.      status = ssc_ControllerStatus( cntroller )
  176.      D0                             D0
  177.  
  178.      int ssc_ControllerStatus(int cntroller);
  179.  
  180.  FUNCTION
  181.      This function reads controller's status. When invalid controller ID
  182.      number has been given, function does not return an error code. Instead,
  183.      it gives as a result: "controller not available" (SSC_CTRLR_NA).
  184.  
  185.  INPUTS
  186.      cntroller - controller's ID number (0-31)
  187.  
  188.  RESULT
  189.      status - Mini SSC II status:
  190.          SSC_CTRLR_NA     = not available
  191.          SSC_CTRLR_BUSY   = busy
  192.          SSC_CTRLR_READY  = ready
  193.          SSC_CTRLR_LOCKED = locked
  194.  
  195.  NOTES
  196.      Mini SSC II does not support status queries or any feedback. Status
  197.      information provided by this function is therefore based on the software
  198.      status (minissc.library status) and not on the actual hardware state.
  199.  
  200.  SEE ALSO
  201.      ssc_ControllerRange()
  202.      ssc_ServoStatus()
  203.  
  204. minissc.library/ssc_FreeController                   minissc.library/ssc_FreeController
  205.  
  206.  NAME
  207.      ssc_FreeController -- Frees occupied controller
  208.  
  209.  SYNOPSIS
  210.      error = ssc_FreeController( cntroller )
  211.      D0                          D0
  212.  
  213.      int ssc_FreeController(int cntroller);
  214.  
  215.  FUNCTION
  216.      This function frees occupied Mini SSC II controller and all its
  217.      occupied servos.
  218.  
  219.  INPUTS
  220.      cntroller - controller's ID number (0-1)
  221.  
  222.  RESULT
  223.      error - an error code:
  224.          0 = no errors
  225.          1 = not a valid controller ID
  226.          2 = can't free controller: it is busy
  227.  
  228.  SEE ALSO
  229.      ssc_ControllerSettings()
  230.      ssc_ControllerStatus()
  231.      ssc_OccupyController()
  232.  
  233. minissc.library/ssc_FreeServo                             minissc.library/ssc_FreeServo
  234.  
  235.  NAME
  236.      ssc_FreeServo -- Frees occupied servo
  237.  
  238.  SYNOPSIS
  239.      error = ssc_FreeServo( servo )
  240.      D0                     D0
  241.  
  242.      int ssc_FreeServo(int servo);
  243.  
  244.  FUNCTION
  245.      This function frees occupied servo.
  246.  
  247.  INPUTS
  248.      servo - servo ID number (0-15)
  249.  
  250.  RESULT
  251.      error - an error code:
  252.          0 = no errors
  253.          1 = can't free servo: it is busy or does not exists
  254.  
  255.  SEE ALSO
  256.      ssc_OccupyServo()
  257.      ssc_ServoSettings()
  258.      ssc_ServoStatus()
  259.  
  260. minissc.library/ssc_GetAPosition                       minissc.library/ssc_GetAPosition
  261.  
  262.  NAME
  263.      ssc_GetAPosition -- Gets absolute position of a servo
  264.  
  265.  SYNOPSIS
  266.      position = ssc_GetAPosition( servo )
  267.      D0                           D0
  268.  
  269.      int ssc_GetAPosition(int servo);
  270.  
  271.  FUNCTION
  272.      This function reads current servo position. Result is the servo's
  273.      absolute position (0-254).
  274.  
  275.  INPUTS
  276.      servo - servo's ID number (0-254)
  277.  
  278.  RESULT
  279.      position - absolute position of a servo (0-254)
  280.          -1 = can't get position. Servo is not occupied
  281.  
  282.  NOTES
  283.      Servo must be occupied before position can be read.
  284.  
  285.  SEE ALSO
  286.      ssc_GetPosition()
  287.  
  288. minissc.library/ssc_GetPosition                         minissc.library/ssc_GetPosition
  289.  
  290.  NAME
  291.      ssc_GetPosition -- Gets position of a servo
  292.  
  293.  SYNOPSIS
  294.      position = ssc_GetPosition( servo )
  295.      D0                          D0
  296.  
  297.      float ssc_GetPosition(int servo);
  298.  
  299.  FUNCTION
  300.      This function reads current servo position. Result is the servo's
  301.      position in degrees (0-180).
  302.  
  303.  INPUTS
  304.      servo - servo's ID number (0-254)
  305.  
  306.  RESULT
  307.      position - servo position in degrees (0-180)
  308.          -1 = can't get position. Servo is not occupied
  309.  
  310.  NOTES
  311.      Servo must be occupied before position can be read.
  312.  
  313.  SEE ALSO
  314.      ssc_GetAPosition()
  315.  
  316. minissc.library/ssc_Move                                       minissc.library/ssc_Move
  317.  
  318.  NAME
  319.      ssc_Move -- Moves servo in proportion to current position
  320.  
  321.  SYNOPSIS
  322.      position = ssc_Move( servo, displacement )
  323.      D0                   D0     D1
  324.  
  325.      float ssc_Move(int servo, float displacement);
  326.  
  327.  FUNCTION
  328.      This function moves servo in proportion to its current position.
  329.      Negative displacement value moves servo anticlockwise and positive value
  330.      clockwise.
  331.      When called, the related servo will be moved to the calculated position
  332.      as quickly as possible.
  333.  
  334.  INPUTS
  335.      servo - servo's ID number (0-15)
  336.      displacement - displacement value:
  337.          negative value = moves servo anticlockwise the amount of given
  338.          degrees
  339.          posisitive value = moves servo clockwise the amount of given
  340.          degrees
  341.  
  342.  RESULT
  343.      position - new servo position:
  344.          -1 = invalid servo ID number
  345.          -2 = calculated new servo position is out of range
  346.  
  347.  NOTES
  348.      Displacement value refers to degrees as a position value. See
  349.      SetPosition() function.
  350.  
  351.  SEE ALSO
  352.      ssc_AMove()
  353.      ssc_SetPosition()
  354.  
  355. minissc.library/ssc_OccupyController               minissc.library/ssc_OccupyController
  356.  
  357.  NAME
  358.      ssc_OccupyController -- Occupies servo controller
  359.  
  360.  SYNOPSIS
  361.      error = ssc_OccupyController( cntroller, commmode, ctrlmode )
  362.      D0                            D0         D1        D2
  363.  
  364.      int ssc_OccupyController(int cntroller,int commmode,int ctrlmode);
  365.  
  366.  FUNCTION
  367.      This function occupies one Mini SSC II controller for your use.
  368.      Connection between your Amiga and Mini SSC II is one way only: from
  369.      Amiga to Mini SSC II. You can send servo positioning commands to the
  370.      Mini SSC II but you can not read any information from the controller or
  371.      reconfigure it through the connection.
  372.      It is very important that you tell to the minissc.library on what
  373.      communication mode and control mode the Mini SSC II is configured by
  374.      using this function. Otherwise servos are not positioned correctly or
  375.      controller might not work at all.
  376.  
  377.        +--------------------+-----------+  +--------------+-------+----------+
  378.        ! COMMUNICATION MODE ! BAUD RATE !  ! CONTROL MODE ! RANGE ! ACCURACY !
  379.        +--------------------+-----------+  +--------------+-------+----------+
  380.        ! low                !   2400    !  ! narrow       |   90° !   0.36°  !
  381.        ! high               !   9600    !  ! wide         !  180° !   0.72°  !
  382.        +--------------------+-----------+  +--------------+-------+----------+
  383.  
  384.      Mini SSC II has two communication modes and two control modes for
  385.      servos. Communication mode indicates how fast computer can send
  386.      positioning commands to the controller(s) and the control mode indicates
  387.      what motion range and accuracy servos operate on.
  388.      Narrow control mode limits servo freedom to 90° while wide mode allows
  389.      180° movements. It is advisable to use narrow mode if you have servos
  390.      which can not move through a full 180-degree range (see
  391.      ssc_ChangeServoSettings() and ssc_OccupyServo() functions for how to
  392.      customize a single servo's motion range) or you need the best possible
  393.      movement accuracy which Mini SSC II can provide.
  394.      It is possible to chain several Mini SSC II controllers together and
  395.      thus control more than 8 servos. These chained controllers can have
  396.      different control mode settings, but the communication modes may not
  397.      differ because controllers share the same serial port. When you occupy
  398.      a controller the given communication mode overwrites all other
  399.      controllers' communication modes for the reason given above.
  400.      See the Mini SSC II manual for how to configure controller.
  401.  
  402.  INPUTS
  403.      cntroller - controller's ID number (0-31) to be occupied
  404.      commmode - communication rate:
  405.          SSC_COMMMODE_LOW  = low; baud rate is 2400
  406.          SSC_COMMMODE_HIGH = high; baud rate is 9600
  407.      ctrlmode - range of motion:
  408.          SSC_CTRLMODE_NARROW = narrow;
  409.              allows 90° movements with the accuracy of 0.36°
  410.          SSC_CTRLMODE_WIDE   = wide;
  411.              allows 180° movements with the accuracy of 0.72°
  412.  
  413.  RESULT
  414.      error - an error code:
  415.          0 = no errors
  416.          1 = controller has already been occupied
  417.          2 = parameter(s) out of range
  418.  
  419.  NOTES
  420.      When setting communication and control mode use always definitions
  421.      included in minissc.h file:
  422.          SSC_COMMMODE_LOW
  423.          SSC_COMMMODE_HIGH
  424.          SSC_CTRLMODE_NARROW
  425.          SSC_CTRLMODE_WIDE
  426.  
  427.  SEE ALSO
  428.      ssc_ChangeServoSettings()
  429.      ssc_ControllerRange()
  430.      ssc_ControllerStatus()
  431.      ssc_FreeController()
  432.      ssc_OccupyServo()
  433.  
  434. minissc.library/ssc_OccupyServo                         minissc.library/ssc_OccupyServo
  435.  
  436.  NAME
  437.      ssc_OccupyServo -- Occupies a servo
  438.  
  439.  SYNOPSIS
  440.      error = ssc_OccupyServo( servo, range )
  441.      D0                       D0     D1
  442.  
  443.      int ssc_OccupyServo(int servo, float range);
  444.  
  445.  FUNCTION
  446.      By default all servos are disabled. In order to use a servo you must
  447.      first occupy it by using this function.
  448.      Required parameters are servo ID number (0-254) and servo's motion range.
  449.      Mini SSC II controller sets the same maximum motion range to all servos
  450.      (90 or 180 degrees). When occupying a servo you can customize the
  451.      servo's motion range within the controller's limits. If controller's
  452.      motion range is 90° you can, for example, set servo number 0 motion range
  453.      to 45° and servo number 1 to 22°. Values exeeding controller's limit are
  454.      not allowed.
  455.  
  456.  INPUTS
  457.      servo - servo ID number (0-254)
  458.      range - range of motion (0-180)
  459.  
  460.  RESULT
  461.      error - an error code:
  462.          0 = no errors
  463.          1 = invalid servo number
  464.          2 = servo has already occupied
  465.          3 = out of range
  466.          4 = can't initialize servo
  467.  
  468.  NOTES
  469.      Servo's range can never exceed controller's range.
  470.  
  471.  SEE ALSO
  472.      ssc_FreeServo()
  473.      ssc_OccupyController()
  474.  
  475. minissc.library/ssc_Reset                                     minissc.library/ssc_Reset
  476.  
  477.  NAME
  478.      ssc_Reset -- Resets a servo
  479.  
  480.  SYNOPSIS
  481.      error = ssc_Reset( servo )
  482.      D0                 D0
  483.  
  484.      int ssc_Reset(int servo);
  485.  
  486.  FUNCTION
  487.      This function moves servo to its initial position (center).
  488.  
  489.  INPUTS
  490.      servo - servo ID number (0-254)
  491.  
  492.  RESULT
  493.      error - an error code:
  494.          0 = no errors
  495.          1 = can't reset servo. It's not ready
  496.  
  497.  SEE ALSO
  498.      ssc_AMove()
  499.      ssc_Move()
  500.      ssc_ResetAll()
  501.      ssc_SetAPosition()
  502.      ssc_SetPosition()
  503.  
  504. minissc.library/ssc_ResetAll                               minissc.library/ssc_ResetAll
  505.  
  506.  NAME
  507.      ssc_ResetAll -- Resets all servos
  508.  
  509.  SYNOPSIS
  510.      error = ssc_ResetAll()
  511.      D0
  512.  
  513.      int ssc_ResetAll(void);
  514.  
  515.  FUNCTION
  516.      This function moves all servos to their initial positions.
  517.  
  518.  INPUTS
  519.      None
  520.  
  521.  RESULT
  522.      None
  523.  
  524.  SEE ALSO
  525.      ssc_Reset()
  526.  
  527. minissc.library/ssc_ServoRange                           minissc.library/ssc_ServoRange
  528.  
  529.  NAME
  530.      ssc_ServoRange -- Gets servo's motion range
  531.  
  532.  SYNOPSIS
  533.      range = ssc_ServoRange( servo )
  534.      D0                      D0
  535.  
  536.      float ssc_ServoRange(int servo);
  537.  
  538.  FUNCTION
  539.      This function reads servo's motion range. Result is the current range in
  540.      degrees.
  541.  
  542.  INPUTS
  543.      servo - servo's ID number (0-15)
  544.  
  545.  RESULT
  546.      range - servo's motion range (0-180 degrees):
  547.          -1 = unable to get servo range
  548.  
  549.  SEE ALSO
  550.      ssc_ControllerRange()
  551.      ssc_OccupyServo()
  552.  
  553. minissc.library/ssc_ServoStatus                         minissc.library/ssc_ServoStatus
  554.  
  555.  NAME
  556.      ssc_ServoStatus -- Gets servo's status
  557.  
  558.  SYNOPSIS
  559.      status = ssc_ServoStatus( servo )
  560.      D0                        D0
  561.  
  562.      int ssc_ServoStatus(int servo);
  563.  
  564.  FUNCTION
  565.      This function reads servo's status.
  566.  
  567.  INPUTS
  568.      servo - servo's ID number (0-15)
  569.  
  570.  RESULT
  571.      status - servo's status:
  572.           SSC_SERVO_NA     = not available
  573.           SSC_SERVO_BUSY   = busy
  574.           SSC_SERVO_READY  = ready
  575.           SSC_SERVO_LOCKED = locked
  576.  
  577.  NOTES
  578.      Mini SSC II does not support status queries or any feedback. Status
  579.      information provided by this function is therefore based on the software
  580.      status (minissc.library status) and not on the actual hardware state.
  581.  
  582.  SEE ALSO
  583.      ssc_ControllerStatus()
  584.      ssc_ServoRange()
  585.  
  586. minissc.library/ssc_SetAPosition                       minissc.library/ssc_SetAPosition
  587.  
  588.  NAME
  589.      ssc_SetAPosition -- Moves servo to the new position
  590.  
  591.  SYNOPSIS
  592.      error = ssc_SetAPosition( servo, position )
  593.      D0                        D0     D1
  594.  
  595.      int ssc_SetAPosition(int servo, int position);
  596.  
  597.  FUNCTION
  598.      Servo can be positioned by using this function. It requires two
  599.      parameters: servo ID number (0-254) and absolute position (0-254).
  600.      Servo ID number identifies the servo to be moved and the position
  601.      argument to which position you want to move the servo. When function is
  602.      called, the related servo will be moved to the desired position as
  603.      quickly as possible.
  604.  
  605.  INPUTS
  606.      servo - servo's ID number (0-254)
  607.      position - new absolute position (0-254)
  608.  
  609.  RESULT
  610.      error - an error code:
  611.          0 = no errors
  612.          1 = invalid servo
  613.          2 = invalid position
  614.          3 = transmission error
  615.  
  616.  NOTES
  617.      This is the most accurate way of moving a servo.
  618.  
  619.  SEE ALSO
  620.      ssc_GetAPosition()
  621.      ssc_SetPosition()
  622.  
  623. minissc.library/ssc_SetPosition                         minissc.library/ssc_SetPosition
  624.  
  625.  NAME
  626.      ssc_SetPosition -- Moves servo to the new position
  627.  
  628.  SYNOPSIS
  629.      error = ssc_SetPosition( servo, position )
  630.      D0                       D0     D1
  631.  
  632.      int ssc_SetPosition(int servo, float position);
  633.  
  634.  FUNCTION
  635.      Servo can be positioned by using this function. It requires two
  636.      parameters: servo ID number (0-254) and position in degrees (0-180).
  637.      Servo ID number identifies the servo to be moved and the position
  638.      argument to which position you want to move the servo. When function is
  639.      called, the related servo will be moved to the desired position as
  640.      quickly as possible.
  641.  
  642.  INPUTS
  643.      servo - servo's ID number (0-254)
  644.      position - new servo position in degrees (0-180)
  645.  
  646.  RESULT
  647.      error - an error code:
  648.          0 = no errors
  649.          1 = invalid servo
  650.          2 = invalid position
  651.          3 = transmission error
  652.  
  653.  SEE ALSO
  654.      ssc_GetPosition()
  655.      ssc_SetAPosition()
  656.  
  657.  
  658.